package org.etsi.ttcn.tci;

import org.etsi.ttcn.tri.TriPortId;
import org.etsi.ttcn.tri.TriPortIdList;
import org.etsi.ttcn.tri.TriComponentId;
import org.etsi.ttcn.tri.TriSignatureId;

public interface TciCHRequired extends TciCDRequired {

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciSendConnected has been called.
   * 
   * The TE enques the received value into the local port queue of the indicated
   * receiver component.
   * 
   * @param senderPort
   *          Port identifier at the sending component via which the message is
   *          send.
   * @param receiverComp
   *          Identifier of the receiving component.
   * @param receivedMessage
   *          The value to be enqueued.
   */
  public void tciEnqueueMsgConnected(TriPortId senderPort,
      TriComponentId receiverComp, Value receivedMessage);

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciCallConnected has been called.
   * 
   * The TE enqueues the calls at the local port queue of the indicated receiver
   * component.
   * 
   * @param senderPort
   *          Port identifier at the sending component via which the message is
   *          send.
   * @param receiverComp
   *          Identifier of the receiving component.
   * @param signature
   *          Identifier of the signature of the procedure call.
   * @param parameterList
   *          A list of value parameters which are part of the indicated
   *          signature. The parameters in parameterList are ordered as they
   *          appear in the TTCN-3 signature declaration.
   */
  public void tciEnqueueCallConnected(TriPortId senderPort,
      TriComponentId receiverComp, TriSignatureId signature,
      TciParameterList parameterList);

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciReplyConnected has been called.
   * 
   * The TE enqueues the reply at the local port queue of the indicated receiver
   * component.
   * 
   * @param senderPort
   *          Identifier of the port sending the reply.
   * @param receiverComp
   *          Identifier of the component receiving the reply.
   * @param signature
   *          Identifier of the signature of the procedure call.
   * @param parameterList
   *          A list of value parameters which are part of the indicated
   *          signature. The parameters in parameterList are ordered as they
   *          appear in the TTCN-3 signature declaration.
   * @param returnValue
   *          (Optional) return value of the procedure call.
   */
  public void tciEnqueueReplyConnected(TriPortId senderPort,
      TriComponentId receiverComp, TriSignatureId signature,
      TciParameterList parameterList, Value returnValue);

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciRaiseConnected has been called.
   * 
   * The TE enqueues the exception at the local port queue of the indicated
   * receiver component.
   * 
   * @param senderPort
   *          Identifier of the port sending the reply.
   * @param receiverComp
   *          Identifier of the component receiving the reply.
   * @param signature
   *          Identifier of the signature of the procedure call.
   * @param except
   *          The exception.
   */
  public void tciEnqueueRaiseConnected(TriPortId senderPort,
      TriComponentId receiverComp, TriSignatureId signature, Value except);

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciCreateTestComponentReq has been called. componentType shall be
   * set to the distinct value null if a test component of kind control shall be
   * created.
   * 
   * The TE creates a TTCN-3 test component of the componentType and passes a
   * TriComponentIdType reference back to the CH. The CH communicates the
   * reference back to the remote TE.
   * 
   * @param kind
   *          The kind of component that shall be created, either mtc, ptc or
   *          control.
   * @param componentType
   *          Identifier of the TTCN-3 component type that shall be created.
   * 
   * @return A TriComponentIdType value for the created component
   * 
   * @deprecated the method <code> tciCreateTestComponent</code> with three
   *             parameters has to be used instead
   */
  public TriComponentId tciCreateTestComponent(int kind, Type componentType);

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciCreateNamedTestComponentReq has been called. componentType
   * shall be set to the distinct value null if a test component of kind control
   * shall be created.
   * 
   * The TE creates a TTCN-3 test component of the componentType and passes a
   * TriComponentIdType reference back to the CH. The CH communicates the
   * reference back to the remote TE.
   * 
   * @param kind
   *          The kind of component that shall be created, either mtc, ptc or
   *          control.
   * @param componentType
   *          Identifier of the TTCN-3 component type that shall be created.
   * @param id
   *          a string that contains the (unique) identifier for the component
   *          to be created
   * 
   * @return A TriComponentIdType value for the created component
   * 
   * @deprecated the method <code> tciCreateTestComponent</code> with three
   *             parameters has to be used instead
   */
  public TriComponentId tciCreateNamedTestComponent(int kind,
      Type componentType, String id);

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciStartTestComponentReq has been called.
   * 
   * The TE shall start the indicated behaviour on the indicated component.
   * 
   * @param comp
   *          Identifier of the component to be started. Refers to an identifier
   *          previously created through a call to tciCreateTestComponent
   * @param behavior
   *          Identifier of the behavior to be started on the component.
   * @param parameterList
   *          A list of Values where each value defines a parameter from the
   *          parameter list as defined in the TTCN-3 function declaration of
   *          the function being started. The parameters in parameterList are
   *          ordered as they appear in the TTCN-3 signature of the test case.
   *          If no parameters have to be passed either the null value or an
   *          empty parameterList, i.e. a list of length zero shall be passed.
   */
  public void tciStartTestComponent(TriComponentId comp,
      TciBehaviourId behavior, TciParameterList parameterList);

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciStopTestComponentReq has been called.
   * 
   * The TE shall stop the indicated behaviour on the indicated component.
   * 
   * @param comp
   *          Identifier of the component to be stopped.
   */
  public void tciStopTestComponent(TriComponentId comp);

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciConnect has been called.
   * 
   * The TE shall connect the indicated ports with each other.
   * 
   * @param fromPort
   *          Identifier of the test component port to be connected from.
   * @param toPort
   *          Identifier of the test component port to be connected to.
   */
  public void tciConnect(TriPortId fromPort, TriPortId toPort);

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciDisconnect has been called.
   * 
   * The TE shall disconnect the indicated ports.
   * 
   * @param fromPort
   *          Identifier of the test component port to be connected from.
   * @param toPort
   *          Identifier of the test component port to be connected to.
   */
  public void tciDisconnect(TriPortId fromPort, TriPortId toPort);

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciMapReq has been called.
   * 
   * The TE shall map the indicated ports with each other.
   * 
   * @param fromPort
   *          Identifier of the test component port to be mapped from.
   * @param toPort
   *          Identifier of the test component port to be mapped to.
   */
  public void tciMap(TriPortId fromPort, TriPortId toPort);

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciUnmapReq has been called.
   * 
   * The TE shall unmap the indicated ports.
   * 
   * @param fromPort
   *          Identifier of the test component port to be mapped from.
   * @param toPort
   *          Identifier of the test component port to be mapped to.
   */
  public void tciUnmap(TriPortId fromPort, TriPortId toPort);

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciTestComponentTerminatedReq has been called.
   * 
   * The local TE is notified of the termination of the indicated test component
   * on a remote TE.
   * 
   * @param comp
   *          Identifier of the component that has terminated.
   * @param verdict
   *          Verdict after termination of the component.
   */
  public void tciTestComponentTerminated(TriComponentId comp,
      VerdictValue verdict);

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciTestComponentRunningReq has been called.
   * 
   * The local TE determines whether the indicated component is executing a test
   * behaviour. In case the component is executing a behaviour true will be
   * returned. In any other case, e.g. test component has finished execution, or
   * test component has not been started, etc. false will be returned. After the
   * operation returns the CH will communicate the value back to the remote TE.
   * 
   * @param comp
   *          Identifier of the component to be checked for running.
   * 
   * @return true if the indicated component is still executing a behaviour,
   *         false otherwise
   */
  public boolean tciTestComponentRunning(TriComponentId comp);

  /**
   * This operation is called by the CH at the local TE when at a remote TE a
   * provided tciTestComponentDoneReq has been called.
   * 
   * The local TE determines whether the indicated component has completed
   * executing its test behaviour. In case the component has completed its
   * behaviour true will be returned. In any other case, e.g. test component has
   * not been started, or test component is still executing, false will be
   * returned. After the operation returns the CH will communicate the value
   * back to the remote TE.
   * 
   * @param comp
   *          Identifier of the component to be checked for done.
   * 
   * @return true if the indicated component has completed executing its
   *         behaviour, false otherwise
   */
  public boolean tciTestComponentDone(TriComponentId comp);

  /**
   * This operation can be called by the CH at the local TE when at a remote TE
   * a provided tciGetMTCReq has been called.
   * 
   * The local TE determines whether the MTC is being executed at the local TE.
   * If the mtc executes on the local TE the component id of the mtc is being
   * returned. In case the mtc is not executed on the local TE the distinct
   * value null will be returned. The operation will have no effect on the
   * execution of the MTC. After the operation returns, the CH will communicate
   * the value back to the remote TE.
   * 
   * @return A TriComponentIdType value of the mtc if the MTC executes on the
   *         local TE, the distinctvalue null otherwise.
   */
  public TriComponentId tciGetMTC();

  /**
   * This operation can be called by the CH at the local TE when at a remote TE
   * a provided tciExecuteTestCaseReq has been called.
   * 
   * The local TE determines whether static connections to the SUT and the
   * initialization of communication means for TSI ports should be done.
   * 
   * @param TestCaseId
   *          A test case identifier as defined in the TTCN-3 module.
   * @param tsiPortList
   *          tsiPortList contains all ports that have been declared in the
   *          definition of the system component for the test case, i.e. the TSI
   *          ports. If a system component has not been explicitly defined for
   *          the test case, then the tsiPortList contains all communication
   *          ports of the MTC test component. The ports in tsiPortList are
   *          ordered as they appear in the respective TTCN-3 component type
   *          declaration. If no ports have to be passed either the null value
   *          or an empty tsiPortList, i.e. a list of length zero shall be
   *          passed.
   */
  public void tciExecuteTestCase(TciTestCaseId TestCaseId,
      TriPortIdList tsiPortList);

  /**
   * This operation can be called by the CH at the local TE when at a remote TE
   * a provided tciResetReq has been called.
   * 
   * The TE can decide to take any means to reset the test system locally.
   */
  public void tciReset();

  /**
   * This operation shall be called by the CH at the local TE when at a remote
   * TE a provided tciCreateTestComponentReq has been called. componentType
   * shall be set to the distinct value null if a test component of kind control
   * shall be created. name shall be set to the distinct value null if no name
   * is given in the TTCN-3 create statement.
   * 
   * The TE creates a TTCN-3 test component of the componentType and passes a
   * TriComponentIdType reference back to the CH. The CH communicates the
   * reference back to the remote TE.
   * 
   * @param kind
   *          The kind of component that shall be created, either MTC, PTC or
   *          CONTROL.
   * @param componentType
   *          Identifier of the TTCN-3 component type that shall be created.
   * @param name
   *          Name of the component that shall be created
   * @return A TriComponentIdType value for the created component.
   */
  public TriComponentId tciCreateTestComponent(int kind, Type componentType,
      String name);

  /**
   * This operation shall be called by the CH at the local TE when at a remote
   * TE a provided <code>tciKillTestComponentReq</code> has been called.
   * 
   * The TE stops the behaviour on the indicated component if necessary and
   * transfers it into the killed state.
   * 
   * @param component
   *          Identifier of the component to be killed.
   */
  public void tciKillTestComponent(TriComponentId component);

  /**
   * This operation shall be called by the CH at the local TE when at a remote
   * TE a provided <code>tciTestComponentAliveReq</code> has been called.
   * 
   * The local TE determines whether the indicated component is alive. After the
   * operation returns, the CH will communicate the value back to the remote TE.
   * 
   * @param component
   *          Identifier of the component to be checked for being alive.
   * @return <code>true</code> if the indicated component is alive, false
   *         otherwise.
   */
  public boolean tciTestComponentAlive(TriComponentId component);

  /**
   * This operation shall be called by the CH at the local TE when at a remote
   * TE a provided <code>tciTestComponentKilledReq</code> has been called.
   * 
   * The local TE determines whether the indicated component is in the killed
   * state. If it is, true will be returned. In any other case, false will be
   * returned. After the operation returns, the CH will communicate the value
   * back to the remote TE.
   * 
   * @param component
   *          Identifier of the component to be checked for being killed.
   * @return <code>true</code> if the indicated component has been killed,
   *         false otherwise.
   */
  public boolean tciTestComponentKilled(TriComponentId component);

} // TciCHRequired
